next - previous - toc

# 2.3. Structure Definition

### Concept

The structure definition is used to model the data structure you want to display in the editor.
A structure definition is a tree structure consisting of structure definition elements. There are two types of elements : statements and data field definitions. A statement may contain other elements whereas a data field definition is a leaf in the tree and may not contain other elements. If the structure definition contains no errors it is compiled into a view.

#### Statements

A root statement is compiled into one data frame, the root frame of the resulting view.

- Root Statement
  The RootStatement is the root element of the structure definition. There can only be one and you cannot delete it. It contains infomation like author, view definition name and a short description.

A case statement is compiled into zero or one view elements.

- Case Statement
  Case Statements are used to define a conditional branch in the compilation process. A Case Statement contains a pointer into the data. This pointer is evaluated during compilation and the resulting data is compared against the defined cases. Each case is a data to structure definition element mapping. The structure definition elements used in the Case Statement all have to be children of this Case Statement and can be either Statements or Data Field Definitions. If no case matches the data the default case is choosen.
  There is one special predefined case in each case statement named "--- None ---".

A repeat statement is compiled into 0-n data frames.

- Repeat Statement
  You can think of a Repeat Statement as an array with variable length. The length can be
  - Static
    Specifing the length of the array before the compilation, independent of the data.
  - Pointer
    Defines a pointer into the underlying data. The pointer is then evaluated during compilation to yield the length

- Repeat Statement Until Offset
  The compiler tries to fit in as many Frames as possible until a certain offset is reached. The offset is calculated by a defining a location and an alignment.
  maximal offset = location + (n * alignment).
  The alignment can
  - Static
    Specifing the alignment before the compilation, independent of the data.
  - Pointer
    Defines a pointer into the underlying data. The pointer is then evaluated during compilation to yield the alignment.

- Repeat Statement Until Delimiter
  The compiler tries to fit in as many Frames as possible until a delimiter is reached.
  If the delimiter has a size of zero bits, it is never found and the remaining bits, till the end of the data are used.

#### Data Field Definitions

A Data Encoding Field Definition is compiled into exactly one Data Encoding Field.

- Data Encoding Field Definition
  Field size is specified before compilation. Use it if you know the size of the field beforehand.
  - Static
    Specifing the size of the array before the compilation.
  - Pointer
    Defines a pointer into the underlying data. The pointer is then evaluated during compilation to yield the length

- Field Until Offset Definition
  The compiler sizes the resulting field as large as necessary to align the next data frame to a certain offset.
  The offset is calculated by a defining a location and an alignment.
  offset = location + (n * alignment).
  The alignment can
  - Static
    Specifing the alignment before the compilation, indepent of the data.
  - Pointer
    Defines a pointer into the underlying data. The pointer is then evaluated during compilation to yield the alignment.
  Use: Use it to make sure the next fields starts at a certain alignment, e.g paddings of the transported data in network packets.

- Field Until Delimiter Definition
  The compiler looks for a certain bitcombination, the delimiter, starting from the current offset. The resulting DataField is has a bitsize from the current offset till the start of the delimiter.
  If the delimiter has a size of zero bits, it is never found and the remaining bits, till the end of the data are used.
  Use: Used to model a datastream with an end marker, e.g. C-Style String delimited by '0'.

A Map Field Definition is compiled into one Map Field

- Map Field Definition
  A MapField Definition is compiled into a MapField. You can define a String to Data mapping which is then used to display and edit the data via a combobox.
  Use: All map fields could be simulated using a DataEncodingField. But the map field is more comftable to edit and provides more information in the form of a value name. Use it if you want to model a field with a very small amount of sensible values where you want to tag each value with a informative name. Instead of using a Data Encoding Field to display one bit flag use a map field to describe the effect of the values.

### View Definition Editing

Dynamic data views are recompiled after each change to the data. The recompilation can be turned by disabling the "Compile View" checkbox.
Each data view has an offset where the structure definition starts. This offset is used as the bitoffset of the first structure node when the structure is rendered. The offset can be locked to the current selection offset by enabling the Lock checkbox. If the offset is locked the offset of the structure is always the current selection offset (If the offset change did not originate from this dataview). If it is unlocked you can manually change the structure offset.

Clicking on a structure definition element will display the corresponding configuration dialog on the right side. After changing the element click on the apply button to make the changes take effect or on the cancel button to undo the changes.
New Insert -> New Add Above -> New Add Below Cut Copy Paste (Insert) Paste (Add Above) Paste (Add Below) Delete

On the buttom you can see two tabs
Validation
Before the structure definition is compiled into a view it has to be valid. The validation tab displays a list of errors in the structure definition which have to be corrected before the view is compiled. By clicking on the error you can select the corresponding structure definition element in the structure tree.
Compiler Output
The compiler output tab provides detailed information about the compilation process. This can be useful if you want to debug complex structure definitions. By clicking on a compiler message you can select the corresponding structure definition element in the structure tree.

### Element Configuration

#### Root Statement

Example:

#### Case Statement

The data offset has to be a structure definition element before this case statement.
The data size must be greater than 0 bits.
Example: The case statement evalutes the protocol field in an ip packet to chose correct view definition. The protocol field has a length of 1 byte, and the defined cases are UDP and TCP. If none of those two protocols are used the default branch is choosen.

#### Repeat Statement

This repeat statement is compiled into `length` data frames.
Example: The repeat statement is compiled into on data frame with the name "access-flags".

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by a multiplication and then an addition (subtraction).
The minimum number of repeats is zero.
Example: The number of repeats is stored in a field called constant-pool-count. This field is evaluated as an unsigned big endian number.

#### Repeat Until Offset Statement

This repeat statement is compiled into `length` data frames.
Example: The repeat statement is compiled into on data frame with the name "access-flags".

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by a multiplication and then an addition (subtraction).
The minimum number of repeats is zero.
Example: The number of repeats is stored in a field called constant-pool-count. This field is evaluated as an unsigned big endian number.

#### Repeat Until Delimiter Statement

Example:

### Fields

#### Data Encoding Field Definition

Example:

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by a multiplication and then an addition (subtraction).
The minimum bitSize is zero.
Example: The data encoding field displays the data inside an udp packet. The length of the packet is stored int a field called length. The length is in bytes, so we have to multiply by 8 to get bits. Then we have to substract the headersize of the udp packet (8 bytes) to get the data size.

#### Repeat Until Offset Field Definition

Example:

Example:

#### Repeat Until Delimiter Field Definition

Example: This is the definition for a c-style string. The delimiter is 0x00 and we display the result in ascii. We want to include the delimiter in the displayed data so we modify the calculated bitsize by adding 1 byte.

#### Map Field Definition

Example: The Operating System byte in the gzip structure. It is 1 byte long and there are 8 possible mappings defined.

next - previous - toc